MacFormat 1996 February/macformat-034.iso/mac/Shareware City/Developers/appe Windows 2.03/About appe Windows

Text File | 1995-12-07 | 14.0 KB | 321 lines | [TEXT/R*ch]

appe Windows 2.03
=================
If you have seen the Speech Manager, then you know that a background
only application can put a window onto the screen (contrary to popular
belief). The new Text Services Manager in System 7.1 offers documented
hooks for creating, disposing, and handling floating windows. These
windows are layer independent (they are floating above all programs and
windows), and can work without patching traps (well, a quick jGNEFilter,
but no traps).

This program demonstrates a shell application that puts a TSM window onto
the screen, and intercepts update, click, and key events. You can use
"sample win.c" and "sample drag.c" to see how to write your own handlers,
and easily add your desired functionality within a few hours. If you don't
care to look behind the scenes, you simply write the handlers from the
templates. If you want to see how it really works, you can lift the curtains
and look in the other functions for yourself.

The program can work as a foreground or background-only application. The
software is distributed as a foreground app, but the process to convert a
program to background app is to set the "Background Only" flag in the
'SIZE' resource (or Project Flags) and to make a system extension, you
should change the file type from 'APPL' to 'appe'. I have added a
drag-n-drop utility to convert between foreground and background apps, as
well as a file describing the differences.

I like the close box on floater windows, because its an easy way to quit
the program without relying on a quit Apple Event. I have added support
for hiding windows with Cmd-Escape, and to respond to screen savers and
programs that take over the screen (hide the menu bar).

Other programs that use this shell include: ObiWan, Extensions Strip,
HoverBar, Virtual, and NotifyMail. Note: that Apple software uses the
layer manager in undocumented ways to get the same effect for software
such as AppleGuide, Control Strip, and the Speech Manager.


Bug Fixes/Changes
=================

2.01 -> 2.03  (2.02 was not released to the public)
    * Updated the TestScreenSaver() function to count to 3 before
      hiding/showing the window, which reduces flicker and stops
      the window from acting strangely during PopupMenuSelect().
    * The jGNEFilter helper sets the current app's A5-world (not
      ours) so that it can call FindServiceWindow(), and we don't
      need to repeatedly test PtInRgn().
    * Replaced the Fat WDEF with 68K and PPC parts to reduce footprint.
    * Fixed a memory leak with RmveResource() in Prefs code.
    * The sample drag handlers now setup and restore our A5-world.
    * Updated the process description for creating a Fat Binary.
    * Dropped the Symantec C code duplication for archive size.
      If you need help porting AppeWin, drop me a line.
    * Updated the bundled TSM Fix from 1.02 to 1.03. See the associated
      ReadMe file for relevant changes.
    * Updated documentation and comments.

2.0 -> 2.01
    * Moved the jGNEFilter code from a constant string to a 'jGNE' resource
      that gets loaded and called as before. This removes the conditional
      template filter (which I have placed in an additional text file).
      I got enough mail about the mechanism that I gave in to clean design.
    * Rebuilt the notification system so that it properly cleans up in both
      the casual and ExitToShell() notification.
    * Tightened up the Prefs code (it was over 2 years old) and even got
      rid of the *gasp* goto's.
    * Reordered the main event loop a bit (swapped a few lines), but made no
      major changes.
    * Tracked down an incompatibility with the 68k-CFM extension that came
      with the OpenDoc DR2 release. Its actually a bug in the 68k-CFM alpha
      that bombs when loading the Fat WDEF. The solution is to update/remove
      the CFM extension, or to use the 68k Infinity WDEF in both the 68k and
      Fat versions of AppeWin. Kewl - Not my bug!
    * Updated documentation and comments.


Legal Stuff
===========
Its yours if you like it. This shell is free for you to modify and
expand upon. I would like it if you tell me if you use this, but you
are under no obligation. Likewise, this library is provided as is --
I fixed up all the bugs I could find/create, so I could use it myself --
but that doesnt necessarily mean its fit for wiping the toilet seat. :)

The enclosed extension "TSM Fix" is intended to fix problems with the
jGNEFilter missing clicks bug. This INIT is also free, to be distributed
with (or without) any software you have written.

In addition, the enclosed utility "appe <-> APPL" is useful so that you
only have to distribute a single binary form. Again, the program is free
to be redistributed at your whim.

The cool floating window WDEF used is the Infinity Windoid by Troy Gaul.
The WDEF is free, but you should read the accompanying documentation and
download the full Infinity Windoid package -- it really rox!  PS - You
may consider distributing the appropriate WDEF (68K, PPC, Fat) with each
version of your program. As stated above, the sample window code now picks
the appropriate binary, which is included separately for each project.


Using the library
=================
In scanning the source for the program, there are several key areas
that you should recognize. These gotchas are important things to
remember when modifying or adding to the source.

main.c

    Faceless background applications seem to require additional stack
    space. I found that 16k of additional stack seems to work. BTW,
    you want keep the memory footprint down (people don't like memory
    hogs) but not too small or you will have heap space problems. I
    had to fine tune my demo apps to work well in limited memory space.

    In a background-only application, the only Toolbox initialization
    call that you should make is InitGraf() to setup the QD globals.
    InitWindows() plays with the layer manager in a bad way, and
    should be avoided.

    Use Gestalt() to check the runtime environment, and exit gracefully
    with a Notification Mgr dialog.

    The event loop sucks incoming events from both WaitNextEvent() and
    from a queue of forwarded events from the Event Filter. These are
    dispatched automatically, as well as resolving any pending update
    events.

notify.c

    A simple installer and cleanup code for posting notifications safely,
    even if we are about to quit. Also set/clear a flag to keep floaters
    from obscuring important notices (since Notification Mgr. interferes
    with our forwarded event mechanism). BTW, if you can come up with a
    better way to dispose the memory allocated using inline code (no
    resources, etc), I would like to hear.

filter.c

    The jGNEFilter is the best way to intercept the events directed
    at our window. We check mouse and key events for relevance, and
    then forward them them to the application's event loop. In this
    version, the only context you get is a valid globals world --
    you CAN'T handle user or update events here. They must be done
    from our (complete and full) context.

    Note: the jGNEFilter may miss occasional mouse-downs. Its a bug
    in the OS, and you need to look at my "TSM Fix" for a patch that
    rememdies the problem.

    Our floaters dont get update events either, so we manually
    check the update region of our window and call the update
    routine. We have to check every event because update events
    aren't necessarily posted when just our window needs
    drawing.

    Key events can be intercepted or passed through at your discretion.
    By default, only Cmd-Escape is applicable and it toggles the
    visibility of the floaters. (This would be a useful feature for all
    similar apps to implement, please?)

    (v2.0) Updated the TestScreenSaver() function to be so much smarter
    and work from within the jGNEFilter and our own context. (2.03) The
    saver is even smarter now, and does not cause window flicker during
    most game startup sequences and when calling PopUpMenuSelect().

    (v2.03) MouseDowns are now tracked properly with FindServiceWindow(),
    thanks to proper A5 management code. Keep in mind that FSW() is a CPU
    Hog, and should not be called for every idle event -- one user found
    that doing so would *double* the time spent in the whole jGNE chain.

patches.c

    The current TSM does not create a Color Window for us, so by default
    we patch NewWindow to enable the desired functionality. Although this
    violates our promise of patch-free operation, it gives us color --
    so lose or leave it at your whim.

    (v2.0) Add a patch to ExitToShell() that cleans up if any unexpected
    errors occur (esp. while debugging). Again, its up to you if you want
    this in your final product -- but I consider it essential.

floaters.c

    The floater functionality parallels NewWindow(), CloseWindow(), and
    DisposeWindow() routines. When creating a floater, you should also
    specify callbacks to handle events or close requests. In addition, you
    can pick a "Hot Application" in which the floater will be visible (and
    hidden at all other times) or pass zero to remain visible at all times.
    This is a great way to give specialized information about a particular
    program without modifying it.

    Utility routines let you walk the internal window list and extract
    additional information, either by window lookup or by index. These are
    used internally for updating or hiding/showing floaters, but the sample
    window routines are free to use them.

    ShowHide and Update routines let you select a particular window, or
    (by passing a NIL WindowPtr) walk the list of all our floaters.

    Handling events or closing all windows are sent to dispatch routines
    that can find the proper handlers and forward the little events along.

sample win.c

    When creating the window, we manage a set of prefs that keep track
    how many windows we have creating. This lets us offset each new
    window, and give it an incremental title across launches.

    The sample window code implements the necessary callbacks that
    receive incoming window events and close imperatives. That code is
    responsible then for handling clicks, hotkeys, and updates.

    Controls like scroll bars or other window-activation sensitive
    elements should always be active in floaters, since all floaters
    are considered active regardless of position in window list.

    The content text for the sample windows are stored off the RefCon, but
    you should do anything you like for the refcon or drawing routines.

sample drag.c

    Hey, its just a demo. You can try it out, expand on it, or just rip
    it out depending on what kind of utility you are writing. It supports
    sending text data and receiving both text data and text files.

    (2.03) Now pass along an A5-world to the drag handlers, so that we
    don't step on anyone's toes.

Compiling Fat Apps

    Since you see 2 projects, one for 68K and one for PPC, you may not
    see how to combine the files to make Fat application.  The trick I
    used was to compile both 68K and PPC versions -- which should be
    identical except where the real code is located (68K='CODE'+'DATA'
    resources, PPC=Data Fork & 'cfrg' rsrc.) Duplicate the PPC binary, then
    use ResEdit to copy over the 'CODE', 'DATA', and 68K 'WDEF' (if you
    use it) resources from the 68K binary to the new Fat version.
    Voila, both 68K and PPC can run the right code. Note, that an
    earlier ReadMe left a few steps out of this process -- DOH!

    Again, I have replaced the Fat WDEF for the 68K and PPC parts to
    reduce memory footprint. You should consider it for your program.

Things Left Undone

    Although a programming guru in my own right, I have not had time or
    energy to investigate certain issues that really should be handled
    and discussed in this type of sample project. If you are going to
    use this software and have insights into any of the following topics,
    please drop me a line so that I can make use of your knowledge:
    Palette Manager interactions with the floaters, Balloon Help, etc.

    Also, I am told that SetCursor() behavior differs between Sys 7.5.x
    and earlier systems. Under older system software, the foreground
    app will not know about your window and may "fight" you by calling
    SetCursor() repeatedly even over your TSM floater (THINK C is very
    bad about it). Under Sys7.5 and later, SetCursor() is patched so
    that an app cannot call SetCursor() within a TSM floater -- even
    your program. The code as it sits does not attempt to deal with this,
    but consider that doing it right will involve installing another
    patch on SetCursor() and special case each situation.

    In the next release, I hope to add code to make "ascending" and
    "descending" floaters that transition between normal windows in a
    layer and TSM floaters. I think I can do it by editing code within
    the "black box" functions -- almost transparently to the actual
    event-handling code. More on this later.


Credits

    It's about time I make acknowledgements to the programmers and
    everyone else who have contributed their time to tracking down my
    bugs and making the program robust. Just like the credits at a
    movie, you can leave now if you or a relative are not listed:

    * Peter Lewis, who helped turn this from a skanky hack into an
      almost legitimate hack by sending bug reports and problems on
      a daily basis.

    * Guy Fullerton, whose HoverBar program tested the limits of my
      rewrite, and who introduced my AppeWindows to more people than
      I even know.

    * Ammon Skidmore, who has spent almost as much time in Macsbug
      as I have trying to figure out how to work around, and still
      be compatible with, System (and other) Software: Balloon Help,
      Text Services Manager, and SetCursor.

    * Ed Wynne, who gets to keep me on the straight and narrow and
      has to listen to every off-the-wall suggestion I make. How
      could I ever release a program or hack without his help?

... and others who have sent in bug reports or helped out:
    * Peter Bierman
    * Mason Bliss
    * Roberto Cattaneo
    * Chris Evans
    * Troy Gaul
    * Mark Gerl
    * Dair Grant
    * Scott Gruby
    * Joshua Juran
    * Mike Smith
    * Andrew Thaler


Finally, I want this to be a stable mechanism for something that you
shouldn't be able to do. Despite the interface guidelines, there may
be a use for doing this. Please send me bug reports and suggestions
for improving this tool.

Matt Slot, [e-mail] - 12/5/95
<http://www.sils.umich.edu/~fprefect/>